[−][src]Crate serde_cbor

CBOR and serialization.

Usage

Serde CBOR supports Rust 1.31 and up. Add this to your Cargo.toml:

[dependencies]
serde_cbor = "0.10"

Storing and loading Rust types is easy and requires only minimal modifications to the program code.

use serde_derive::{Deserialize, Serialize};
use std::error::Error;
use std::fs::File;

// Types annotated with `Serialize` can be stored as CBOR.
// To be able to load them again add `Deserialize`.
#[derive(Debug, Serialize, Deserialize)]
struct Mascot {
    name: String,
    species: String,
    year_of_birth: u32,
}

fn main() -> Result<(), Box<dyn Error>> {
    let ferris = Mascot {
        name: "Ferris".to_owned(),
        species: "crab".to_owned(),
        year_of_birth: 2015,
    };

    let ferris_file = File::create("examples/ferris.cbor")?;
    // Write Ferris to the given file.
    // Instead of a file you can use any type that implements `io::Write`
    // like a HTTP body, database connection etc.
    serde_cbor::to_writer(ferris_file, &ferris)?;

    let tux_file = File::open("examples/tux.cbor")?;
    // Load Tux from a file.
    // Serde CBOR performs roundtrip serialization meaning that
    // the data will not change in any way.
    let tux: Mascot = serde_cbor::from_reader(tux_file)?;

    println!("{:?}", tux);
    // prints: Mascot { name: "Tux", species: "penguin", year_of_birth: 1996 }

    Ok(())
}

There are a lot of options available to customize the format. To operate on untyped CBOR values have a look at the Value type.

Type-based Serialization and Deserialization

Serde provides a mechanism for low boilerplate serialization & deserialization of values to and from CBOR via the serialization API. To be able to serialize a piece of data, it must implement the serde::Serialize trait. To be able to deserialize a piece of data, it must implement the serde::Deserialize trait. Serde provides an annotation to automatically generate the code for these traits: #[derive(Serialize, Deserialize)].

The CBOR API also provides an enum serde_cbor::Value.

Packed Encoding

When serializing structs or enums in CBOR the keys or enum variant names will be serialized as string keys to a map. Especially in embedded environments this can increase the file size too much. In packed encoding the keys and variants will be serialized as variable sized integers. The first 24 entries in any struct consume only a single byte! To serialize a document in packed encoding use ser::to_(vec|writer)_packed, deserialization works without any changes.

Self describing documents

In some contexts different formats are used but there is no way to declare the format used out of band. For this reason CBOR has a magic number that may be added before any document. The _sd (for selfd*escribe) append the magic number before documents.

Examples

Read a CBOR value that is known to be a map of string keys to string values and print it.

use std::collections::BTreeMap;
use serde_cbor::from_slice;

let slice = b"\xa5aaaAabaBacaCadaDaeaE";
let value: BTreeMap<String, String> = from_slice(slice).unwrap();
println!("{:?}", value); // {"e": "E", "d": "D", "a": "A", "c": "C", "b": "B"}

Read a general CBOR value with an unknown content.

use serde_cbor::from_slice;
use serde_cbor::value::Value;

let slice = b"\x82\x01\xa1aaab";
let value: Value = from_slice(slice).unwrap();
println!("{:?}", value); // Array([U64(1), Object({String("a"): String("b")})])

Serialize an object.

use std::collections::BTreeMap;
use serde_cbor::to_vec;

let mut programming_languages = BTreeMap::new();
programming_languages.insert("rust", vec!["safe", "concurrent", "fast"]);
programming_languages.insert("python", vec!["powerful", "friendly", "open"]);
programming_languages.insert("js", vec!["lightweight", "interpreted", "object-oriented"]);
let encoded = to_vec(&programming_languages);
assert_eq!(encoded.unwrap().len(), 103);

Deserializing data in the middle of a slice

use serde_cbor::Deserializer;

let data: Vec<u8> = vec![
    0x66, 0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72, 0x66, 0x66, 0x6f, 0x6f, 0x62,
    0x61, 0x72,
];
let mut deserializer = Deserializer::from_slice(&data);
let value: &str = serde::de::Deserialize::deserialize(&mut deserializer)
    .unwrap();
let rest = &data[deserializer.byte_offset()..];
assert_eq!(value, "foobar");
assert_eq!(rest, &[0x66, 0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72]);

`no-std` support

Serde CBOR supports building in a no_std context, use the following lines in your Cargo.toml dependencies:

[dependencies]
serde = { version = "1.0", default-features = false }
serde_cbor = { version = "0.10", default-features = false }

Without the std feature the functions from_reader, from_slice, to_vec, and to_writer are not exported. To export from_slice and to_vec enable the alloc feature. The alloc feature uses the alloc library and requires at least version 1.36.0 of Rust.

Note: to use derive macros in serde you will need to declare serde dependency like so:

serde = { version = "1.0", default-features = false, features = ["derive"] }

Serialize an object with no_std and without alloc.

use serde::Serialize;
use serde_cbor::Serializer;
use serde_cbor::ser::SliceWrite;

#[derive(Serialize)]
struct User {
    user_id: u32,
    password_hash: [u8; 4],
}

let mut buf = [0u8; 100];
let writer = SliceWrite::new(&mut buf[..]);
let mut ser = Serializer::new(writer);
let user = User {
    user_id: 42,
    password_hash: [1, 2, 3, 4],
};
user.serialize(&mut ser)?;
let writer = ser.into_inner();
let size = writer.bytes_written();
let expected = [
    0xa2, 0x67, 0x75, 0x73, 0x65, 0x72, 0x5f, 0x69, 0x64, 0x18, 0x2a, 0x6d,
    0x70, 0x61, 0x73, 0x73, 0x77, 0x6f, 0x72, 0x64, 0x5f, 0x68, 0x61, 0x73,
    0x68, 0x84, 0x1, 0x2, 0x3, 0x4
];
assert_eq!(&buf[..size], expected);

Deserialize an object.

#[derive(Debug, PartialEq, Deserialize)]
struct User {
    user_id: u32,
    password_hash: [u8; 4],
}

let value = [
    0xa2, 0x67, 0x75, 0x73, 0x65, 0x72, 0x5f, 0x69, 0x64, 0x18, 0x2a, 0x6d,
    0x70, 0x61, 0x73, 0x73, 0x77, 0x6f, 0x72, 0x64, 0x5f, 0x68, 0x61, 0x73,
    0x68, 0x84, 0x1, 0x2, 0x3, 0x4
];

// from_slice_with_scratch will not alter input data, use it whenever you
// borrow from somewhere else.
// You will have to size your scratch according to the input data you
// expect.
use serde_cbor::de::from_slice_with_scratch;
let mut scratch = [0u8; 32];
let user: User = from_slice_with_scratch(&value[..], &mut scratch)?;
assert_eq!(user, User {
    user_id: 42,
    password_hash: [1, 2, 3, 4],
});

let mut value = [
    0xa2, 0x67, 0x75, 0x73, 0x65, 0x72, 0x5f, 0x69, 0x64, 0x18, 0x2a, 0x6d,
    0x70, 0x61, 0x73, 0x73, 0x77, 0x6f, 0x72, 0x64, 0x5f, 0x68, 0x61, 0x73,
    0x68, 0x84, 0x1, 0x2, 0x3, 0x4
];

// from_mut_slice will move data around the input slice, you may only use it
// on data you may own or can modify.
use serde_cbor::de::from_mut_slice;
let user: User = from_mut_slice(&mut value[..])?;
assert_eq!(user, User {
    user_id: 42,
    password_hash: [1, 2, 3, 4],
});

Limitations

While Serde CBOR strives to support all features of Serde and CBOR there are a few limitations.

Tags are ignored during deserialization and can't be emitted during serialization. This is because Serde has no concept of tagged values. See: #3
Unknown simple values cause an UnassignedCode error. The simple values False and True are recognized and parsed as bool. Null and Undefined are both deserialized as unit. The unit type is serialized as Null. See: #86
128-bit integers can't be directly encoded in CBOR. If you need them store them as a byte string. See: #77

Modules

de	Deserialization.
error	When serializing or deserializing CBOR goes wrong.
ser	Serialize a Rust data structure to CBOR data.
value	CBOR values, keys and serialization routines.

Structs

Deserializer	A Serde `Deserialize`r of CBOR data.
Error	This type represents all possible errors that can occur when serializing or deserializing CBOR data.
Serializer	A structure for serializing Rust values to CBOR.
StreamDeserializer	Iterator that deserializes a stream into multiple CBOR values.

Enums

Value

The Value enum, a loosely typed way of representing any valid CBOR value.

Functions

from_reader	Decodes a value from CBOR data in a reader.
from_slice	Decodes a value from CBOR data in a slice.
to_vec	Serializes a value to a vector.
to_writer	Serializes a value to a writer.

Type Definitions

Result

Alias for a Result with the error type serde_cbor::Error.